​
Prerequisites

Before attempting to install Ditto, ensure you have Rust installed via rustup:
1

If you don’t have the rustup command, install it via the official Install Rust documentation.
2

If you already have rustup, ensure it’s updated to the latest version:
rustup self update
3

Now, verify you have both rustc and cargo available in your shell:
rustc --version
cargo --version

​
Creating a New Project

Using Cargo, create a new binary project: 
cargo new --bin my_project_name

​
Adding the Ditto Dependency

Add the Ditto SDK to your Rust project:
1

Visit docs.rs/dittolive-ditto to find the latest version of the Rust SDK, or the version you would like to use.
2

From the Cargo.toml file located in the root of your project, add a dependency on dittolive-ditto. We recommend using the "=x.y.z" semver syntax to prevent implicit upgrades.
[dependencies]
dittolive-ditto = "=4.10.0"
3

Visit the Rust Compatibility Map page to find the Rust Toolchain version you need based on the SDK version you chose.
4

Create a rust-toolchain file next to your Cargo.tomland paste the Rust toolchain version you looked up from the compatibiltiy map
1.81
5

Save the Cargo.toml and rust-toolchain files, then check that you can build and run the executable with cargo run:
$ cargo run
info: syncing channel updates 
...
    Finished dev [unoptimized + debuginfo] target(s) in 0.05s
     Running `target/debug/my_project_name`
Hello, world!
The first time running cargo build or cargo run after updating the rust-toolchain file, you should see the “info: syncing channel updates” message. This is rustup magically installing the toolchain you specified in rust-toolchain behind the scenes.

​
Organizing Filesystem Structure

When organizing the end-user device storage directory, adhere to a filesystem structure that is clean, consistent, and easily maintained. For guidelines to keep organized, see Components and Organization Best Practices.

​
Components and Organization Best Practices

The following table provides an overview of the components that make up your app’s filesystem structure and best practices for organizing the files on the filesystem of the end-user device:
ComponentBest Practice
AppRoot/AppExecutableThe executable file for your app that, unless explicitly specified, the Ditto SDK is statically linked to: - All other files and directories should be relative to this location. - Maintain a clear separation between this executable file and other libraries. - If desired, use the Ditto SDK as a separate shared library. (See Optional Dynamic Linking)
AppRoot/libdittoffi.dllThe Ditto SDK binary library file linking your Cargo for Rust project with Ditto.¹ By default, the Ditto SDK is statically linked to your executable. However, if desired, you can configure your build for dynamic linking by specifying the shared library version of the Ditto SDK. (See Optional Dynamic Linking)
AppRoot/ditto_data/The base directory designated for Ditto-backed app data stored locally on the end-user device: - Organize all app data within this directory rather than across the entire filesystem for your project. - Maintain a clear and consistent directory structure for your project.
¹The path and format of the Ditto SDK binary library file vary by app target. For example, .dylib for macOS and .dll for Windows. (See Binary Library Path Formats)

​
Setting Up Optional Dynamic Linking

If using the Ditto SDK as a separate library from your app’s executable, ensure that, during the build process, the linker can locate the Ditto SDK shared library and link it with your app:
1

From the linker configuration for your project, specify the path to the Ditto SDK shared binary library.
For an overview of file paths and file extensions by target platform, see Binary Library Path Formats.
For example, to configure for the macOS target, configure the linker flag to locate the Ditto SDK shared binary library (libdittoffi.dylib) for compilation, use @executable_path to specify a relative path from the executable to the library:
@executable_path/../libdittoffi.dylib
2

Before distributing your app, ensure the Ditto SDK shared binary library is included and accessible at the specified location and configured for your linker:
target/<profile>/build/dittolive-ditto-sys<hash>/out

​
Binary Library Path Formats

The following table provides an overview of the different file extensions for the binary Ditto library by target platform:
TargetFormatDescription
Linux.soShared object (SO)
macOS.dylibDynamic library (DL)
Windows.dllDynamic link library (DLL)

​
Troubleshooting

During the build process, you may encounter the following error message indicating the Ditto SDK build.rs script failed to locate and download the native static library (dittoffi) containing the Ditto binary appropriate for your target: 
"error: could not find native static library dittoffi, perhaps an -L flag is missing". What should I do?

​
Diagnosing build.rs Failures

The build.rs script that executes at build is responsible for setting up your build environment and ensuring necessary dependencies, including the Ditto SDK, are correctly configured and accessible for compilation. However, several factors, such as connectivity issues and misconfigured settings, can cause this script to fail. To diagnose this issue, check the following logs for errors: 
 target/<profile>/build/dittolive-ditto-sys-<hash>/stderr

​
Resolving build.rs Failures

To resolve this issue, perform the following troubleshooting steps:
1

Ensure your internet connection is live and the Ditto SDK version number is correct.
2

Using a command-line tool like file, otool, and readelf, as follows, inspect the downloaded library located in the build cache to determine if its properties meet the requirements for integration into your Rust project:
file libdittoffi.dylib

otool -L libdittoffi.dylib

readelf -a libdittoffi.so
3

Verify the issue is resolved by re-running cargo build and ensuring it executes successfully.